home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Tampa Bay Amiga Group / TBAG - Tampa Bay Amiga Group's Disk of the Month #70 (199x)(Merlin's Software - Amiganuts United)(PD).zip / TBAG - Tampa Bay Amiga Group's Disk of the Month #70 (199x)(Merlin's Software - Amiganuts United)(PD).adf / Docs / PopUpMenu.docs < prev    next >
Text File  |  1992-07-14  |  18KB  |  521 lines
  1.  
  2.     PopUpMenu V4.3 by Martin Adrian           28/1 -92
  3.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4.  
  5.     Introduction
  6.     ~~~~~~~~~~~~
  7.     Are you using QMouse, DMouse, or HeliosMouse and "always" get the wrong
  8.      menues when you press the mousebutton?
  9.     Have you ever needed pop-up menues for your Amiga?
  10.  
  11.     The solution: PopUpMenu
  12.  
  13.     What is it ?
  14.     ~~~~~~~~~~~~
  15.     This small program makes it possible for You to use popupmenues with
  16.      every program using standard intuition menues.
  17.      ~~~~~
  18.     The popup-menues works just like the standard pull-down menues for both
  19.      the user (multiple selections, checkmarks, commandkeys) and the
  20.      programmer (MENUPICK and MENUVERIFY).
  21.      All intuition menu-flags (COMMSEQ, HIGHBOX, MENUTOGGLE ...)
  22.      are fully supported.
  23.  
  24.     Features:
  25.     ~~~~~~~~~
  26.     * The menues will not pop-up if any of the following conditions are true.
  27.  
  28.        1) No window is active.                  \
  29.        2) The active window has no menues.          |
  30.        3) The active window has the flag RMBTRAP set. |-  Same as Intuition
  31.        4) The active window has a requester open.     /
  32.  
  33.        5) The mousepointer is in the screens menubar.
  34.       (standard pull-down menues will appear)
  35.  
  36.        6) You are pressing any other mousebutton (left or middle).
  37.  
  38.        7) A stringgadget is active. (Only intuition knows how to deselect them).
  39.       You will have to use pull-down menues.
  40.  
  41.     * You may select if the menues should pop-up when you are holding a
  42.       qualifier key on Your keyboard down or not.
  43.  
  44.     * Click-menues: You make Your selection with the select-button instead of
  45.             holding down the menubutton (works like I*M PC menues).
  46.             Excellent for programs with many menues (e.g. RSDemo).
  47.  
  48.     * PopUpMenu can show a small arrow if a menuitem has subitems.
  49.  
  50.     * MenuItems can be centered around the menu (To minimize mouse movements).
  51.  
  52.     * The program remembers the last menu selected.
  53.     (Works only with items selected with PopUpMenues and does not remember
  54.     different windows).
  55.  
  56.     * PopUpMenu has an intuition interface for setting options.
  57.  
  58.  
  59.    Starting PopUpMenu
  60.    ~~~~~~~~~~~~~~~~~~
  61.    To use the program put the file `PopUpMenu' and 'PopUpMenu.info'
  62.      in your current directory.
  63.  
  64.    ----------------------   From CLI:  ------------------------
  65.    To turn on the pop-up menues just type:
  66.  
  67.      1> Run PopUpMenu  [options]
  68.  
  69.    Default options are     -O -N -P -K19
  70.  
  71.    I don't know how much stack exec and intuition needs.
  72.      PopUpMenu is using less than 800 bytes.
  73.      Setting stack to 3000 should be OK.
  74.  
  75.    >>>>>> Warning! PopUpMenu is not self-detaching any more. <<<<<<
  76.  
  77.    Arp users can type:
  78.  
  79.      1> ARun PopUpMenu [Options] NOIO STACK 2500
  80.  
  81.      (I suppose RunBack can do the same thing)
  82.  
  83.    If PopUpMenu is already installed you can change or look at the
  84.      current options by starting PopUpMenu again.
  85.  
  86.      1> PopUpMenu  [options]
  87.      PopUpMenu     Current options = -N -P -K19
  88.  
  89.      (Use "-O" option to open the options window)
  90.  
  91.    To turn off PopUpMenu use option "-X" from the CLI or use the
  92.      "Remove PopUpMenu" gadget in the option window.
  93.  
  94.      1> PopUpMenu -X
  95.  
  96.    ----------------------   From WB:   -----------------------
  97.    Click the PopUpMenu icon.
  98.    (WB 2.0 users may move the icon to the WBStartup drawer.
  99.     Don't forget the "DONOTWAIT" flag in the TOOLTYPES field)
  100.  
  101.    To set the options
  102.  
  103.      1. Put the string 'ARG=' in the TOOLTYPES field,
  104.     followed by the CLI options.
  105.  
  106.     Example: ARG=-C -N -O- -K19
  107.  
  108.    (If you enter an illegal option the option window will show up with
  109.     the default options set when You start PopUpMenu)
  110.  
  111.      2. Put the long names in the TOOLTYPES field.
  112.     (I think WB2.0 users can skip the '=')
  113.  
  114.          Example: CLICKMENUES=
  115.               POPNOQUAL=
  116.               NOOPTIONWINDOW=
  117.               HOTKEY=19
  118.  
  119.        (Unkonown or misspelled options will be ignored)
  120.  
  121.    When PopUpMenu is running, is the icon locked. This means that You can't
  122.    change any options from workbench.
  123.  
  124.    To change the options use any of the following ways.
  125.  
  126.    1) Start the program from workbench again. (The option window will show up)
  127.    2) Use the hotkey to open the option window.
  128.  
  129.    You may use all options from the workbench but the "-X" and "-H" options
  130.    are not very useful. ("-X -O-" will do nothing at all)
  131.  
  132.    Options
  133.    ~~~~~~~
  134.  
  135.    - - - - - - - - - Click-menues - - - - - - - - -
  136.    CLI: enable     -C        WB: enable     CLICKMENUES
  137.    CLI: disable  -C-        WB: disable  STDMENUES      [default]
  138.  
  139.      If a program has a lot of menues it may be difficult
  140.      to select the one You want.  Click-menues lets You
  141.      slow and easy select it.
  142.  
  143.         1. Press and release the menubutton.
  144.         2. The menues will show up.
  145.         3. Select the menu You want with the selectbutton.
  146.         4. Select the menuitem or subitem in the same way.
  147.         5. You may cancel the menu selection by pressing
  148.            the menubutton again.
  149.  
  150.    - - - - - - - - Sub-item pointer - - - - - - - -
  151.    CLI: enable     -P        WB: enable     SUBPOINTER      [default]
  152.    CLI: disable  -P-        WB: disable  NOSUBPOINTER
  153.  
  154.      PopUpMenu will show a small arrow if a menuitem
  155.      has any sub-items.
  156.  
  157.    - - - - - - - - Show single menu - - - - - - - -
  158.    CLI: enable     -S        WB: enable     SHOWSINGLE
  159.    CLI: disable  -S-        WB: disable  DONTSHOWSINGLE  [default]
  160.  
  161.      If a window has only one menu, PopUpMenu shows it
  162.      together with the menuitems.  To disable this feature
  163.      turn this option on.
  164.  
  165.             Show single       Don't
  166.               +-----+         +------+
  167.         +-----|Items|         |Menu  |
  168.         |Menu |     |         |Items |
  169.         +-----|     |         |        |
  170.               |     |         |        |
  171.               +-----+         |        |
  172.                      +------+
  173.    - - - - - - - - Centered menuitems - - - - - -
  174.    CLI: enable     -I        WB: enable     ITEMSCENTERED
  175.    CLI: disable  -I-        WB: disable  ITEMSTOP     [default]
  176.  
  177.      When PopUpMenu displays the menu-items it usually
  178.      places the top item next to the menu.    With this
  179.      option on, the items are centered around the menu.
  180.  
  181.          Top           Centered
  182.           +------+           +------+
  183.           |      |           |     +-----+
  184.           |      |           |     |Items|
  185.           |     +-----+       |     |     |
  186.           |Menu |Items|       |Menu |     |
  187.           +-----|      |       +-----|     |
  188.             |      |         |     |
  189.             |      |         +-----+
  190.             |      |
  191.             +-----+
  192.  
  193.    - - - Pop-up when no qualifier is pressed - - -
  194.    CLI: enable     -N        WB: enable     POPNOQUAL     [default]
  195.    CLI: disable  -N-        WB: disable  DONTPOPNOQUAL
  196.  
  197.    - - - Pop-up when a qualifier is pressed - - -
  198.    CLI: enable     -Q        WB: enable     POPWITHQUAL
  199.    CLI: disable  -Q-        WB: disable  DONTPOPWITHQUAL [default]
  200.  
  201.      These options controls when the menues should pop-up.
  202.          (Qualifier = SHIFT, ALT, AMIGA, CTRL)
  203.  
  204.      You may set both (menues will always pop-up) or none (menues
  205.      will never pop-up).
  206.  
  207.    - - - - - - - Open option window - - - - - - -
  208.    CLI: enable     -O        WB: enable     OPTIONWINDOW     [default]
  209.    CLI: disable  -O-        WB: disable  NOOPTIONWINDOW
  210.  
  211.      Open the PopUpMenu option window.
  212.  
  213.    - - - - - - - - - - Set Hotkey - - - - - - - - - -
  214.    CLI: enable     -K##        WB: enable     HOTKEY=##     [default = 19 => 'P']
  215.  
  216.      Use this option to set the hot-Key.  If the hot-key is pressed
  217.      together with CTRL and ALT the PopUpMenu option window will
  218.      show up on the Workbench screen.
  219.      ## means the hex code for the key.  (default = 'P')
  220.  
  221.    - - - - - - - - Remove PopUpMenu - - - - - - - -
  222.    CLI: enable     -X
  223.  
  224.     This option will remove PopUpMenu from memory.
  225.  
  226.    - - - - - - - - - - Show help - - - - - - - - - -
  227.    CLI: enable     -H
  228.     Display a help message. (The help message will also appear if
  229.     PopUpMenu can't understand Your options)
  230.  
  231.  
  232.    PopUpMenu option window
  233.    ~~~~~~~~~~~~~~~~~~~~~~~
  234.    When You select the -O option, press the hot-key or starts the program
  235.      from workbench a second time, the PopUpMenu option window will show up on
  236.      Your workbench screen.
  237.  
  238.      In this window You may enable or disable any option with a mouse-click
  239.      or by pressing the corresponding key.
  240.  
  241.      The hot-key can be changed by pressing CTRL + ALT + the desired key.
  242.  
  243.    There are four more gadgets in the window:
  244.    Name         Key        Action
  245.    ~~~~         ~~~        ~~~~~~
  246.    Use           Return  - Closes the window and uses the currently selected
  247.                  options.
  248.    Reset         R       - Resets any changes made.
  249.    Cancel        Esc    - Closes the  window but doesn't change any options.
  250.                  (Same as Reset + Use)
  251.    Remove PopUpMenu  X       - Closes window and removes PopUpMenu from memory.
  252.                  (No "Are You sure" requester will show up)
  253.  
  254.  
  255.    Differences from Intuition:
  256.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  257.    Bad:
  258.      Drag-select is not supported (i never use it), Use Multiple selcet.
  259.  
  260.      Menu flag MENUTOGGLED is not supported.
  261.  
  262.      Intuition draws the menues off-screen and then swaps them to the screen.
  263.      PopUpMenu draws the menues on the screen.    (I don't want to create a
  264.      rastport just to draw them)
  265.  
  266.    Good:
  267.      The mousepointer does not stop while menuwindows are opened or closed.
  268.      (Makes it easier to select items when your amiga has much to do)
  269.  
  270.    Good or bad ?
  271.      PopUpMenu does not remove any inputevents (RAWKEY, MOUSEMOVE ...)
  272.      while the menues are shown.  (Intuition needs these to move the
  273.      mousepointer etc.)
  274.  
  275.      If a menu does not have menuitems, intuition shows a small empty
  276.      itemwindow.  PopUpMenu does not show anything at all.
  277.  
  278.  
  279.    Same as Intuition:
  280.    ~~~~~~~~~~~~~~~~~~
  281.  
  282.    * PopUpMenu handles multiple selection as silly as intuition.
  283.        Don't select a menuitem more than once or the checkmarks may be moved
  284.        to the wrong item.
  285.  
  286.  
  287.   Program size
  288.   ~~~~~~~~~~~~
  289.   The program size is much bigger than before but don't worry the memory
  290.     usage is almost the same (~10K).  The code for option parsing and the
  291.     option window are overlayd.  The code and data for them will only be
  292.     loaded only when needed.
  293.  
  294.    Distribution
  295.    ~~~~~~~~~~~~
  296.  
  297.    This version of the PopUpMenu program is released as Public Domain.
  298.                             ~~~~~~~~~~~~~~
  299.      This program may be used, copied, included in a library or commercial
  300.      product as long as You don't do it for profit.
  301.      (Please include PopUpMenu.doc in the copy)
  302.  
  303.      You may also use the source in your own programs (if You can read it),
  304.      If You intend to do a similar popupmenu-program with it please let me
  305.      know so we can cooperate instead of compete.
  306.  
  307.  
  308.    Warnings:
  309.    ~~~~~~~~~
  310.  
  311.    1. If a string gadget is active when You press the menu button,
  312.      You will recieve pull-down menues.  (Only intition or You can deselect
  313.      a string gadget)
  314.      A strange effect shows up if You double click the menu button in the
  315.      req.library file requester.  The first click will deselect the string
  316.      gadget and activate the pull-down menues.    The second click will give You
  317.      popup-menues.  But after a short time (1 second or so) the string gadget
  318.      will be activated again and Your menu selection will be neglected until
  319.      You deselects the gadget.
  320.  
  321.    2. QMouse has an inputhandler that sends messages (i think) to its task
  322.      when the mouse is moved over window borders.  When the screen is locked
  323.      QMouse can't activate the window under the mouse but the messages will
  324.      continue to come.    When the menu selection is done Qmouse will handle all
  325.      the messages and activate the windows one by one (The window titles will
  326.      flash).  The problem is most annying when using Click-menues.
  327.      I think the problem is the same with Dmouse, HeliosMouse,
  328.      SumMouse etc.
  329.      A first look at the new commodities shows that they are even worse.
  330.      They activate the windows from within their inputhandler. (see 6.)
  331.  
  332.    3. Some people have reported that PopUpMenu 3.X does not work with PageSetter
  333.      (both version 1 and 2).  I have tested PS1.2 (a french version) but it
  334.      crashes always on my Amiga (with or without PopUpMenu).  I think PS
  335.      corrupts the FreeMemList when I enter the texteditor.
  336.  
  337.    4. Yves Benoit in France, who is the lucky (?!) owner of a A3000, told me
  338.      he had some problems when putting PopUpMenu in the startup-sequence.
  339.      I don't know anything about KS 2.0 so i don't know what the problem is.
  340.  
  341.    5. Don't use PopUpMenu with version number 2.XX since they may end up with
  342.      a spectacular crash and a visit to the guru.
  343.  
  344.    6. Intuition is a very big inputhandler (i think), this means that intuition
  345.      will lockup the input.device if it (intuition) tries to draw something
  346.      (i.e activate a window) on a locked screen.  This will lead to a deadlock
  347.      since my program is waiting for mouse-events from the input.device.
  348.      To walk around this I have installed a timer to go off every 0.2s, if
  349.      no inputevents has arrived in this time my program does the following:
  350.  
  351.       1. Remove all displayed menues.
  352.       2. Unlock the screen.
  353.       3. Wait for the input.device to start.
  354.       4. Lock the screen again.
  355.       5. Draw all menues again.
  356.  
  357.      This will make the menues flash once.
  358.  
  359.      (Let's hope intuition works better in kickstart 2.0)
  360.  
  361.    7. It is not possible to remove older versions (before 4.0) with
  362.      this program.
  363.  
  364.    8. Some programs draw directly into the screen without using the
  365.      layers.library.  Using PopUpMenu on these screens may produce strange
  366.      results.  Only the data on the screen is affected.
  367.      Programs found:  RSDemo, Imploder (4.0)
  368.  
  369.    FUTURE:
  370.    ~~~~~~~
  371.  
  372.     User configurable qualifiers for the hot-key (CTRL+LALT is hard-coded now).
  373.  
  374.     Multiple select with Click-menues.    (Don't know how yet)
  375.  
  376.     AREXX port (?!)
  377.  
  378.     The program only remembers the last menu (not menuitem or subitem) selected.
  379.  
  380.     Many people want's the item and subitems to all show up on the same side.
  381.     In the standard case this shouldn't be any problem but I have to think
  382.     about every case.
  383.       - What if it's impossible to open a big menu on any side ?
  384.       - Sub-items are positioned by the application program not PopUpMenu.
  385.     (Maybe I do it one day)
  386.  
  387.    Author:
  388.    ~~~~~~~
  389.      Martin Adrian
  390.      Rullharvsgatan 3A           (New addres from 1-jun-91)            ..
  391.      S-431 47  Mölndal           (the ö is an 'o' with to dots above -> o )
  392.      SWEDEN
  393.  
  394. USENET:  d5adria@dtek.chalmers.se  ( Until June 1992 )
  395.  
  396.    Thanks to:
  397.     Derek Zahn          for the PopUpMenu program on FishDisk 96
  398.     Commodore          for the Amiga
  399.     Arp - people          for Arp 1.3 & AShell
  400.     Lattice           for the C compiler (5.0)
  401.     My English teatcher
  402.     Anna              my girlfriend
  403.     You              for using this program.
  404.  
  405.  
  406.    New in version 4.3
  407.    ~~~~~~~~~~~~~~~~~~
  408.    For use:
  409.    * Better workbench support.
  410.  
  411.    * Possible to change the hotkey in the option window.
  412.  
  413.    * Option window can be controlled from keyboard.
  414.      (All gadgets have keyboard eqvivalents)
  415.  
  416.    Bugs Fixed:
  417.    * Removed a bug that sometimes cleared 1 bit at position $0014.
  418.  
  419.  
  420.    New in version 4.2
  421.    ~~~~~~~~~~~~~~~~~~
  422.    For safety:
  423.    * Checks that no one has changed SetMenuStrip, ClearMenuStrip, OnMenu, OffMenu
  424.      before they are restored. (If someone has, PopUpMenu waits ~5 seconds
  425.      and then tries again. The PopUpMenu task will not be removed until it is safe
  426.      to do so.    You may start PopUpMenu again)
  427.  
  428.    * My inputhandler now checks if a string gadget is active and if so You will
  429.      get standard pull-down menues.
  430.  
  431.    For Speed:
  432.    * Moved SysBase pointer to the stack. ( = FAST RAM if present)
  433.  
  434.    Bugs fixed:
  435.    * Forgot to change parameters to "HighLight" -> Guru if HIGHIMAGE was used.  (oops!)
  436.  
  437.    New in version 4.1
  438.    ~~~~~~~~~~~~~~~~~~
  439.    For comapbility:
  440.    * MIDRAWN, ISDRAWN, HIGHITEM now supported.
  441.    * MENUSTATE flag supported.
  442.  
  443.    For use:
  444.    * Possible to set options from workbench.
  445.    * Menues no longer flashes when You multiple select a subitem.
  446.    * RMBTRAP is set in the option window.
  447.       (My compiler removed it when compiling with 16-bit ints).
  448.  
  449.    Bugs fixed:
  450.    * Fixed bug that caused a guru if You multiple-selected a disabled item.
  451.    * Fixed bug that always opened the option window. (even with -O- option)
  452.  
  453.    New in version 4.0
  454.    ~~~~~~~~~~~~~~~~~~
  455.    * Command line options.
  456.    * Click menues.
  457.    * + Much more.  Many bugs fixed ( and some new one introduced 8-( ).
  458.  
  459.    New in version 3.7
  460.    ~~~~~~~~~~~~~~~~~~
  461.    For compability:
  462.    * Fixed bug with the checkmark position.
  463.      (Thanks Mark Knibbs)
  464.  
  465.    New in version 3.6
  466.    ~~~~~~~~~~~~~~~~~~
  467.    For compability:
  468.    * PopUpMenu now works when a menu does not have any items.
  469.      (Thanks to Mark Knibbs for finding the bug)
  470.  
  471.    For use:
  472.    * Itemwindow is now positioned in a different way to minimize mousemoves.
  473.      (Thanks to Gael Marziou, France)
  474.  
  475.    New in version 3.5
  476.    ~~~~~~~~~~~~~~~~~~
  477.    For compability:
  478.    * Disabled menues items are now shown.
  479.    * Menues are sorted after their LeftEdge value.
  480.  
  481.    New in version 3.4
  482.    ~~~~~~~~~~~~~~~~~~
  483.    For safety:
  484.    * Now checks to see if screen and window is still present after the
  485.       input.device lockup fix.
  486.    * Rearranged the files so all PopUpMenu hunks shows in Xoper.
  487.       (It should be 3 of them)
  488.  
  489.    For compability:
  490.    * Fixed a small bugs that sometimes made itemwindows to small.
  491.  
  492.    * The program no longer clears the menuitemfield before drawing
  493.       the highimage. (Intuition doesn't)
  494.  
  495.    For Distribution:
  496.    * Now the PopUpMenu.run works (Ver 3.2 didn't  OOPS!).
  497.  
  498.    * Size is now < 7K.
  499.  
  500.    New in version 3.2
  501.    ~~~~~~~~~~~~~~~~~~
  502.    For speed:
  503.    * Some code optimizations (C -> Assembler).
  504.  
  505.    For safety:
  506.    * MENUVERIFY is now fully supported.
  507.    * Forbid() and LockIBase() are now used where needed. (I hope.)
  508.    * Made my own SwapBitsRastPortClipRect.   (No more guru #81000005)
  509.  
  510.    For use:
  511.    * Shows if an item has subitems.
  512.    * Now always shows items & subitems (even if they cover other menuwindows).
  513.    * Now resumes after the input.device lock-up.
  514.  
  515.    For compability:
  516.    * Fixed Fontbug.
  517.  
  518.    New Distrbution:
  519.    * Public Domain.  (i'm not a poor student anymore 8-) )
  520.  
  521.